Inside Macintosh: QuickDraw GX Objects /

Chapter 8 - Tag Objects / Tag Objects Reference

Functions / Manipulating Tag Object Properties

GXGetTag

You can use the GXGetTag function to retrieve the tag type and contents of a tag object.

long GXGetTag(gxTag source, long *tagType, void *data);

source

A reference to the tag object whose contents you want to retrieve.

tagType

A pointer to a value specifying a tag object type. On return, specifies the type of tag object referenced in the source parameter.

data

A pointer to a buffer. On return, the buffer holds the contents of the source tag object.

function result

The size in bytes of the contents of the source tag object.

DESCRIPTION

The GXGetTag function returns the tag type and contents of the source tag object in the tagType and data parameters, respectively. Its function result is the size of the information returned in the data array.

Before calling GXGetTag, you must allocate an array of sufficient size to hold the contents of the tag object. If instead you pass nil for the data parameter, GXGetTag does not return the tag contents, but nonetheless returns (as its function result) the size of the contents. Thus you can make an initial call to GXGetTag to determine the size of buffer to allocate, and then call GXGetTag once more to get the contents.

The GXGetTag function is different from the GXGetTagStructure function in that
it returns a copy of the tag object's contents in a buffer that you have allocated in application memory. The GXGetTagStructure gives you direct access to the contents of a tag object in QuickDraw GX memory.

Although GXGetTag returns the contents of a tag object, it returns no information other than size about the format or organization of the tag's contents. You must know the internal structure of a tag object's contents in order to manipulate it.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
tag_is_nil

SEE ALSO

To replace the tag type and contents of a tag object, use the GXSetTag function, described in the next section.

The GXGetTagStructure function is described on page 8-23.